<?php

/* This file is part of the Phalcon Framework.
 *
 * (c) Phalcon Team <team@phalcon.io>
 *
 * For the full copyright and license information, please view the LICENSE.txt
 * file that was distributed with this source code.
 */
namespace Phalcon\Mvc\Model;

use Phalcon\Mvc\ModelInterface;

/**
 * Phalcon\Mvc\Model\QueryInterface
 *
 * Interface for Phalcon\Mvc\Model\Query
 */
interface QueryInterface
{

    /**
     * Sets the cache parameters of the query
     *
     * @param array $cacheOptions
     * @return QueryInterface
     */
    public function cache(array $cacheOptions): QueryInterface;

    /**
     * Executes a parsed PHQL statement
     *
     * @return mixed
     * @param array $bindParams
     * @param array $bindTypes
     */
    public function execute(array $bindParams = array(), array $bindTypes = array());

    /**
     * Returns default bind params
     *
     * @return array
     */
    public function getBindParams(): array;

    /**
     * Returns the current cache options
     *
     * @return array
     */
    public function getCacheOptions(): array;

    /**
     * Returns default bind types
     *
     * @return array
     */
    public function getBindTypes(): array;

    /**
     * Returns the SQL to be generated by the internal PHQL (only works in SELECT statements)
     *
     * @return array
     */
    public function getSql(): array;

    /**
     * Executes the query returning the first result
     *
     * @param array $bindParams
     * @param array $bindTypes
     * @return ModelInterface
     */
    public function getSingleResult(array $bindParams = array(), array $bindTypes = array()): ModelInterface;

    /**
     * Check if the query is programmed to get only the first row in the resultset
     *
     * @return bool
     */
    public function getUniqueRow(): bool;

    /**
     * Parses the intermediate code produced by Phalcon\Mvc\Model\Query\Lang generating another
     * intermediate representation that could be executed by Phalcon\Mvc\Model\Query
     *
     * @return array
     */
    public function parse(): array;

    /**
     * Set default bind parameters
     *
     * @param array $bindParams
     * @param bool $merge
     * @return QueryInterface
     */
    public function setBindParams(array $bindParams, bool $merge = false): QueryInterface;

    /**
     * Set default bind parameters
     *
     * @param array $bindTypes
     * @param bool $merge
     * @return QueryInterface
     */
    public function setBindTypes(array $bindTypes, bool $merge = false): QueryInterface;

    /**
     * Set SHARED LOCK clause
     *
     * @param bool $sharedLock
     * @return QueryInterface
     */
    public function setSharedLock(bool $sharedLock = false): QueryInterface;

    /**
     * Tells to the query if only the first row in the resultset must be returned
     *
     * @param bool $uniqueRow
     * @return QueryInterface
     */
    public function setUniqueRow(bool $uniqueRow): QueryInterface;
}
